---
name: "pgcopydb snapshot"
section: "1"
platform: "linux"
package: "pgcopydb"
version: "0.17-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pgcopydb snapshot"
---

# pgcopydb snapshot(1)

pgcopydb snapshot pgcopydb snapshot - Create and export a snapshot on the source database The command pgcopydb snapshot connects to the source database and executes a SQL query to export a snapshot. The obtained snapshot is both printed on stdout and also in a file where other pgcopydb commands might expect to find it.

## NAME

pgcopydb snapshot - pgcopydb snapshot

pgcopydb snapshot - Create and export a snapshot on the source database

The command **pgcopydb snapshot** connects to the source database and executes a SQL query to export a snapshot. The obtained snapshot is both printed on stdout and also in a file where other pgcopydb commands might expect to find it.

```
pgcopydb snapshot: Create and export a snapshot on the source database
usage: pgcopydb snapshot  --source ...
  --source                      Postgres URI to the source database
  --dir                         Work directory to use
  --follow                      Implement logical decoding to replay changes
  --plugin                      Output plugin to use (test_decoding, wal2json)
  --wal2json-numeric-as-string  Print numeric data type as string when using wal2json output plugin
  --slot-name                   Use this Postgres replication slot name
```

## OPTIONS

The following options are available to **pgcopydb snapshot**:

- **--source**

  Connection string to the source Postgres instance. See the Postgres documentation for *connection strings* for the details. In short both the quoted form **"host=... dbname=..."** and the URI form **postgres://user@host:5432/dbname** are supported.

- **--dir**

  During its normal operations pgcopydb creates a lot of temporary files to track sub-processes progress. Temporary files are created in the directory specified by this option, or defaults to **${TMPDIR}/pgcopydb** when the environment variable is set, or otherwise to **/tmp/pgcopydb**.

- **--follow**

  When the **--follow** option is used then pgcopydb implements Change Data Capture as detailed in the manual page for *pgcopydb follow* in parallel to the main copy database steps.

  The replication slot is created using the Postgres replication protocol command CREATE\_REPLICATION\_SLOT, which then exports the snapshot being used in that command.

- **--plugin**

  Logical decoding output plugin to use. The default is *test\_decoding* which ships with Postgres core itself, so is probably already available on your source server.

  It is possible to use *wal2json* instead. The support for wal2json is mostly historical in pgcopydb, it should not make a user visible difference whether you use the default test\_decoding or wal2json.

- **--wal2json-numeric-as-string**

  When using the wal2json output plugin, it is possible to use the **--wal2json-numeric-as-string** option to instruct wal2json to output numeric values as strings and thus prevent some precision loss.

  You need to have a wal2json plugin version on source database that supports **--numeric-data-types-as-string** option to use this option.

  See also the documentation for *wal2json* regarding this option for details.

- **--slot-name**

  Logical decoding slot name to use.

- **--verbose**

  Increase current verbosity. The default level of verbosity is INFO. In ascending order pgcopydb knows about the following verbosity levels: FATAL, ERROR, WARN, INFO, NOTICE, DEBUG, TRACE.

- **--debug**

  Set current verbosity to DEBUG level.

- **--trace**

  Set current verbosity to TRACE level.

- **--quiet**

  Set current verbosity to ERROR level.

## ENVIRONMENT

PGCOPYDB\_SOURCE\_PGURI

Connection string to the source Postgres instance. When **--source** is ommitted from the command line, then this environment variable is used.

PGCOPYDB\_OUTPUT\_PLUGIN

Logical decoding output plugin to use. When **--plugin** is omitted from the command line, then this environment variable is used.

PGCOPYDB\_WAL2JSON\_NUMERIC\_AS\_STRING

When true (or *yes*, or *on*, or 1, same input as a Postgres boolean) then pgcopydb uses the wal2json option **--numeric-data-types-as-string** when using the wal2json output plugin.

When **--wal2json-numeric-as-string** is ommitted from the command line then this environment variable is used.

## EXAMPLES

Create a snapshot on the source database in the background:

```
$ pgcopydb snapshot &
[1] 72938
17:31:52 72938 INFO  Running pgcopydb version 0.7.13.gcbf2d16.dirty from "/Users/dim/dev/PostgreSQL/pgcopydb/./src/bin/pgcopydb/pgcopydb"
17:31:52 72938 INFO  Using work dir "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb"
17:31:52 72938 INFO  Removing the stale pid file "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb/pgcopydb.aux.pid"
17:31:52 72938 INFO  Work directory "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb" already exists
17:31:52 72938 INFO  Exported snapshot "00000003-000CB5FE-1" from the source database
00000003-000CB5FE-1
```

And when the process is done, stop maintaining the snapshot in the background:

```
$ kill %1
17:31:56 72938 INFO  Asked to terminate, aborting
[1]+  Done                    pgcopydb snapshot
```

## AUTHOR

Dimitri Fontaine

## COPYRIGHT

2022-2024, Dimitri Fontaine